home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / AddErrInfo.3 next >
Encoding:
Text File  |  1994-12-17  |  5.1 KB  |  131 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) AddErrInfo.3 1.16 94/12/17 16:17:04
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_AddErrorInfo tclc
  12. .BS
  13. .SH NAME
  14. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
  20. .sp
  21. \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
  22. .sp
  23. char *
  24. \fBTcl_PosixError\fR(\fIinterp\fR)
  25. .SH ARGUMENTS
  26. .AS Tcl_Interp *message
  27. .AP Tcl_Interp *interp in
  28. Interpreter in which to record information.
  29. .AP char *message in
  30. Identifying string to record in \fBerrorInfo\fR variable.
  31. .AP char *element in
  32. String to record as one element of \fBerrorCode\fR variable.
  33. Last \fIelement\fR argument must be NULL.
  34. .BE
  35.  
  36. .SH DESCRIPTION
  37. .PP
  38. These procedures are used to manipulate two global variables
  39. that hold information about errors.
  40. The variable \fBerrorInfo\fR holds a stack trace of the
  41. operations that were in progress when an error occurred, and
  42. is intended to be human-readable.
  43. The variable \fBerrorCode\fR holds a list of items that
  44. are intended to be machine-readable.
  45. The first item in \fBerrorCode\fR identifies the class of
  46. .VS
  47. error that occurred (e.g. POSIX means an error occurred in
  48. .VE
  49. a POSIX system call) and additional elements in \fBerrorCode\fR
  50. hold additional pieces of information that depend on the class.
  51. See the Tcl overview manual entry for details on the various
  52. formats for \fBerrorCode\fR.
  53. .PP
  54. The \fBerrorInfo\fR variable is gradually built up as an
  55. error unwinds through the nested operations.
  56. Each time an error code is returned to \fBTcl_Eval\fR
  57. it calls the procedure \fBTcl_AddErrorInfo\fR to add
  58. additional text to \fBerrorInfo\fR describing the
  59. command that was being executed when the error occurred.
  60. By the time the error has been passed all the way back
  61. to the application, it will contain a complete trace
  62. of the activity in progress when the error occurred.
  63. .PP
  64. It is sometimes useful to add additional information to
  65. \fBerrorInfo\fR beyond what can be supplied automatically
  66. by \fBTcl_Eval\fR.
  67. \fBTcl_AddErrorInfo\fR may be used for this purpose:
  68. its \fImessage\fR argument contains an additional
  69. string to be appended to \fBerrorInfo\fR.
  70. For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
  71. to record the name of the file being processed and the
  72. line number on which the error occurred;  for Tcl procedures, the
  73. procedure name and line number within the procedure are recorded,
  74. and so on.
  75. The best time to call \fBTcl_AddErrorInfo\fR is just after
  76. \fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
  77. In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
  78. use the \fBerrorLine\fR field of the interpreter (see the
  79. \fBTcl_Interp\fR manual entry for details).
  80. .PP
  81. The procedure \fBTcl_SetErrorCode\fR is used to set the
  82. \fBerrorCode\fR variable.
  83. Its \fIelement\fR arguments give one or more strings to record
  84. in \fBerrorCode\fR:  each \fIelement\fR will become one item
  85. of a properly-formed Tcl list stored in \fBerrorCode\fR.
  86. \fBTcl_SetErrorCode\fR is typically invoked just before returning
  87. an error.
  88. If an error is returned without calling \fBTcl_SetErrorCode\fR
  89. then the Tcl interpreter automatically sets \fBerrorCode\fR
  90. to \fBNONE\fR.
  91. .PP
  92. \fBTcl_PosixError\fR
  93. .VS
  94. sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
  95. It reads the value of the \fBerrno\fR C variable and calls
  96. \fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the
  97. \fBPOSIX\fR format.
  98. In addition, \fBTcl_PosixError\fR returns a human-readable
  99. .VE
  100. diagnostic message for the error (this is the same value that
  101. will appear as the third element in \fBerrorCode\fR).
  102. It may be convenient to include this string as part of the
  103. error message returned to the application in \fIinterp->result\fR.
  104. .PP
  105. It is important to call the procedures described here rather than
  106. setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
  107. \fBTcl_SetVar\fR.
  108. The reason for this is that the Tcl interpreter keeps information
  109. about whether these procedures have been called.
  110. For example, the first time \fBTcl_AppendResult\fR is called
  111. for an error, it clears the existing value of \fBerrorInfo\fR
  112. and adds the error message in \fIinterp->result\fR to the variable
  113. before appending \fImessage\fR;  in subsequent calls, it just
  114. appends the new \fImessage\fR.
  115. When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
  116. that \fBerrorCode\fR has been set;  this allows the Tcl interpreter
  117. to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
  118. when \fBTcl_SetErrorCode\fR hasn't been called.
  119. .PP
  120. If the procedure \fBTcl_ResetResult\fR is called, it clears all
  121. of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
  122. (but it doesn't actually modify the variables).
  123. If an error had occurred, this will clear the error state to
  124. make it appear as if no error had occurred after all.
  125.  
  126. .SH "SEE ALSO"
  127. Tcl_ResetResult, Tcl_Interp
  128.  
  129. .SH KEYWORDS
  130. error, stack, trace, variable
  131.